---
title: 运行智能体
description: Configure and execute agent workflows with the Runner class
---

import { Aside, Code } from '@astrojs/starlight/components';
import helloWorldWithRunnerExample from '../../../../../../examples/docs/hello-world-with-runner.ts?raw';
import helloWorldExample from '../../../../../../examples/docs/hello-world.ts?raw';
import runningAgentsExceptionExample from '../../../../../../examples/docs/running-agents/exceptions1.ts?raw';
import chatLoopExample from '../../../../../../examples/docs/running-agents/chatLoop.ts?raw';
import conversationIdExample from '../../../../../../examples/docs/running-agents/conversationId.ts?raw';
import previousResponseIdExample from '../../../../../../examples/docs/running-agents/previousResponseId.ts?raw';

智能体本身不会执行任何操作——需要通过 `Runner` 类或 `run()` 工具来**运行**它们。

<Code lang="typescript" code={helloWorldExample} title="Simple run" />

当你不需要自定义 runner 时，也可以使用 `run()` 工具，它会运行一个默认的单例 `Runner` 实例。

或者，你可以创建自己的 runner 实例：

<Code lang="typescript" code={helloWorldWithRunnerExample} title="Simple run" />

运行智能体后，你将收到一个[执行结果](/openai-agents-js/zh/guides/results)对象，其中包含最终输出和完整的运行历史。

## 智能体循环

当你在 Runner 中使用 run 方法时，你需要传入一个起始智能体和输入。输入可以是字符串（被视为用户消息），也可以是输入项列表，即 OpenAI Responses API 中的条目。

然后 runner 会运行一个循环：

1. 使用当前输入调用当前智能体的模型。
2. 检查 LLM 响应。
   - **最终输出** → 返回。
   - **交接** → 切换到新智能体，保留累积的对话历史，转到 1。
   - **工具调用** → 执行工具，将其结果追加到对话中，转到 1。
3. 一旦达到 `maxTurns`，抛出 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror)。

<Aside type="note">
  判断 LLM 输出是否为“最终输出”的规则是：
  产生了具有期望类型的文本输出，且没有工具调用。
</Aside>

### Runner 生命周期

在应用启动时创建一个 `Runner` 并在多个请求间复用。该实例存储全局配置，例如模型提供方和追踪选项。只有在需要完全不同的配置时才创建另一个 `Runner`。对于简单脚本，你也可以调用 `run()`，它在内部使用默认 runner。

## 运行参数

传给 `run()` 方法的输入包括用于启动运行的初始智能体、运行的输入以及一组选项。

输入可以是字符串（被视为用户消息）、[输入项](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem)列表，或在构建[人机协作](/openai-agents-js/zh/guides/human-in-the-loop)智能体时使用的 [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) 对象。

其他选项包括：

| Option     | Default | Description                                                                                                          |
| ---------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| `stream`   | `false` | 如果为 `true`，调用将返回 `StreamedRunResult`，并在模型产生事件时实时发出。                                          |
| `context`  | –       | 转发给每个 tool / guardrail / handoff 的上下文对象。详见[上下文管理](/openai-agents-js/zh/guides/context)。          |
| `maxTurns` | `10`    | 安全上限——达到时抛出 [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror)。 |
| `signal`   | –       | 用于取消的 `AbortSignal`。                                                                                           |

## 流式传输

流式传输允许你在 LLM 运行期间额外接收流式事件。流启动后，`StreamedRunResult` 将包含关于此次运行的完整信息，包括所有新产生的输出。你可以使用 `for await` 循环遍历流式事件。详见[流式传输](/openai-agents-js/zh/guides/streaming)。

## 运行配置

如果你在创建自己的 `Runner` 实例时，可以传入 `RunConfig` 对象来配置 runner。

| Field                       | Type                  | Purpose                                                         |
| --------------------------- | --------------------- | --------------------------------------------------------------- |
| `model`                     | `string \| Model`     | 为运行中的**所有**智能体强制指定特定模型。                      |
| `modelProvider`             | `ModelProvider`       | 解析模型名称——默认使用 OpenAI 提供方。                          |
| `modelSettings`             | `ModelSettings`       | 覆盖单个智能体设置的全局调优参数。                              |
| `handoffInputFilter`        | `HandoffInputFilter`  | 执行交接时修改输入项（如果交接本身未定义）。                    |
| `inputGuardrails`           | `InputGuardrail[]`    | 应用于*初始*用户输入的护栏。                                    |
| `outputGuardrails`          | `OutputGuardrail[]`   | 应用于*最终*输出的护栏。                                        |
| `tracingDisabled`           | `boolean`             | 完全禁用 OpenAI 追踪。                                          |
| `traceIncludeSensitiveData` | `boolean`             | 在仍然发出 span 的情况下，将 LLM/工具的输入与输出从追踪中排除。 |
| `workflowName`              | `string`              | 显示在 Traces 控制台中——有助于归类相关运行。                    |
| `traceId` / `groupId`       | `string`              | 手动指定 trace 或 group ID，而不是由 SDK 自动生成。             |
| `traceMetadata`             | `Record<string, any>` | 附加到每个 span 的任意元数据。                                  |

## 会话 / 聊天线程

每次调用 `runner.run()`（或 `run()` 工具）代表你的应用层对话中的一个**轮次**。你可以自行决定向终端用户展示多少 `RunResult`——有时仅展示 `finalOutput`，有时展示每个生成的条目。

<Code
  lang="typescript"
  code={chatLoopExample}
  title="Example of carrying over the conversation history"
/>

查看[聊天示例](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts)以获取交互版本。

### 服务器托管会话

你可以让 OpenAI Responses API 为你持久化会话历史，而无需在每一轮都发送全部本地记录。这在协调长对话或多项服务时很有用。详情参见[会话状态指南](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses)。

OpenAI 提供两种复用服务器端状态的方式：

#### 1. `conversationId` 表示整个会话

你可以使用[Conversations API](https://platform.openai.com/docs/api-reference/conversations/create) 创建一次会话，然后在每一轮中复用其 ID。SDK 会自动仅包含新生成的条目。

<Code
  lang="typescript"
  code={conversationIdExample}
  title="Reusing a server conversation"
/>

#### 2. 使用 `previousResponseId` 从上一次轮次继续

如果你计划直接从 Responses API 开始，可以用上一次响应返回的 ID 串联每个请求。这样无需创建完整的会话资源，也能在各轮次间保持上下文。

<Code
  lang="typescript"
  code={previousResponseIdExample}
  title="Chaining with previousResponseId"
/>

## 异常

SDK 会抛出一小组可供捕获的错误：

- [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) —— 达到 `maxTurns`。
- [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror) —— 模型产生无效输出（如 JSON 格式错误、未知工具）。
- [`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/inputguardrailtripwiretriggered) / [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/outputguardrailtripwiretriggered) —— 违反护栏。
- [`GuardrailExecutionError`](/openai-agents-js/openai/agents-core/classes/guardrailexecutionerror) —— 护栏执行失败。
- [`ToolCallError`](/openai-agents-js/openai/agents-core/classes/toolcallerror) —— 任一函数工具调用失败。
- [`UserError`](/openai-agents-js/openai/agents-core/classes/usererror) —— 基于配置或用户输入抛出的任何错误。

它们都继承自基础 `AgentsError` 类，该类可能提供 `state` 属性以访问当前运行状态。

以下是处理 `GuardrailExecutionError` 的示例代码：

<Code
  lang="typescript"
  code={runningAgentsExceptionExample}
  title="Guardrail execution error"
/>

运行上述示例时，你将看到如下输出：

```
Guardrail execution failed: Error: Input guardrail failed to complete: Error: Something is wrong!
Math homework guardrail tripped
```

---

## 后续步骤

- 了解如何[配置模型](/openai-agents-js/zh/guides/models)。
- 为你的智能体提供[工具](/openai-agents-js/zh/guides/tools)。
- 添加[护栏](/openai-agents-js/zh/guides/guardrails)或[追踪](/openai-agents-js/zh/guides/tracing)以满足生产就绪要求。
